| +H or +? | Show help screen 0 if this is the only switch |
| +H0 to +H8 | Show help screen 0 to 8 if this is the only switch |
| +?0 to +?8 | Same as +H0 to +H8 |
Note there are no INI style equivalents to these options.
Graphical interface versions of POV-Ray such as Mac or Windows have extensive online help. Other versions of POV-Ray have only a few quick-reference help screens. The +? switch, optionally followed by a single digit from 0 to 8, will display these help screens to the Banner text stream. After displaying the help screens, POV-Ray terminates. Because some operating systems do not permit a question mark as a command line switch, you may also use the +H switch. Note however that this switch is also used to specify the height of the image in pixels. Therefore the +H switch is only interpreted as a help switch if it is the only switch on the command line and if the value after the switch is less than or equal to 8.
| Quality=n | Set quality value to n (0 <= n <= 10) |
| +Qn | Same as Quality=n |
The Quality=nn option or +Qnn switch allows you to specify the image rendering quality. You may choose to lower the quality for test rendering and raise it for final renders. The quality adjustments are made by eliminating some of the calculations that are normally performed. For example settings below 4 do not render shadows. Settings below 8 do not use reflection or refraction. The values correspond to the following quality levels:
| 0,1 | Just show quick colors. Use full ambient lighting only. Quick colors are used only at 5 or below. |
| 2,3 | Show specified diffuse and ambient light. |
| 4 | Render shadows, but no extended lights. 5 Render shadows, including extended lights. |
| 6,7 | Compute texture patterns. |
| 8 | Compute reflected, refracted, and transmitted rays. |
| 9 | Compute halos. |
| 10 | Use radiosity, but do not calculate halos. |
| 11 | Use radiosity and halos. |
The default is 9 if not specified. A value of 10 or 11 turns on radiosity. Radiosity is an additional calculation which computes diffuse inter-reflection. It is an extremely slow calculation that is somewhat experimental. The parameters which control how radiosity calculations are performed are specified in the global_settings {radiosity {...} } statement. See "Miscellaneous Features" for further details.
| Bounding=bool | Turn bounding on/off |
| +MB | Turn bounding on; threshold 25 or prev. amt |
| -MB | Turn bounding off |
| Bounding_Threshold=n | Set bound threshold to n |
| +MBn | Turn bounding on; bound threshold to n |
| -MBn | Turn bounding off; for future threshold to n |
| Light_Buffer=bool | Turn light buffer on/off |
| +UL | Turn light buffer on |
| -UL | Turn light buffer off |
| Vista_Buffer=bool | Turn vista buffer on/off |
| +UV | Turn vista buffer on |
| -UV | Turn vista buffer off |
POV-Ray uses a variety of spatial sub-division systems to speed up ray-object intersection tests. The primary system uses a hierarchy of nested bounding boxes. This system compartmentalizes all finite objects in a scene into invisible rectangular boxes that are arranged in a tree-like hierarchy. Before testing the objects within the bounding boxes the tree is descended and only those objects are tested whose bounds are hit by a ray. This can greatly improve rendering speed. However for scenes with only a few objects the overhead of using a bounding system is not worth the effort. The Bounding=off option or -MB switch allows you to force bounding off. The default value is on.
The Bounding_Threshold=nnn or +MBnnn switch allows you to set the minimum number of objects necessary before bounding is used. The default is +MB25 which means that if your scene has fewer than 25 objects, POV-Ray will automatically turn bounding off because the overhead isn't worth it.
Additionally POV-Ray uses systems known as vista buffers and light buffers to further speed things up. These systems only work when bounding is on and when there are a sufficient number of objects to meet the bounding threshold. The vista buffer is created by projecting the bounding box hierarchy onto the screen and determining the rectangular areas that are covered by each of the elements in the hierarchy. Only those objects whose rectangles enclose a given pixel are tested by the primary viewing ray. The vista buffer can only be used with perspective and orthographic cameras because they rely on a fixed viewpoint and a "reasonable" projection (i.e. lines have to stay lines after the projection).
The light buffer is created by enclosing each light source in an imaginary box and projecting the bounding box hierarchy onto each of its six sides. Since this relies on a fixed light source, light buffers will not be used for area lights.
Reflected and transmitted rays do not take advantage of the light and vista buffer.
The default settings are Vista_Buffer=on or +UV and Light_Buffer=on or +UL. The option to turn these features off is available to demonstrate their usefulness and as protection against unforeseen bugs which might exist in any of these bounding systems.
In general, any finite object and many types of CSG of finite objects will properly respond to this bounding system. In addition blobs and meshes use an additional internal bounding system. These systems are not affected by the above switch. They can be switched off using the appropriate syntax in the scene file (see "Blob" and "Mesh" for details). Text objects are split into individual letters that are bound using the bounding box hierarchy. Some CSG combinations of finite and infinite objects are also automatically bound. The end result is that you will rarely need to add manual bounding objects as was necessary in earlier versions of POV-Ray unless you use many infinite objects.
| Antialias=bool | Turns anti-aliasing on/off |
| +A | Turns aa on with threshold 0.3 or previous amount |
| -A | Turns anti-aliasing off |
| Sampling_Method=n | Sets aa-sampling method (1 or 2) |
| +AMn | Same as Sampling_Method=n |
| Antialias_Threshold=n.n | Sets anti-aliasing threshold |
| +An.n | Sets aa on with aa-threshold at n.n |
| -An.n | Sets aa off (aa-threshold n.n in future) |
| Jitter=bool | Sets aa-jitter on/off |
| +J | Sets aa-jitter on with 1.0 or previous amount |
| -J | Sets aa-jitter off |
| Jitter_Amount=n.n | Sets aa-jitter amount to n.n. If n.n <= 0 aa-jitter is set off |
| +Jn.n | Sets aa-jitter on; jitter amount to n.n. If n.n <= 0 aa-jitter is set off |
| -Jn.n | Sets aa-jitter off (jitter amount n.n in future) |
| Antialias_Depth=n | Sets aa-depth (1 <= n <= 9) |
| +Rn | Same as Antialias_Depth=n |
The ray tracing process is in effect a discrete, digital sampling of the image with typically one sample per pixel. Such sampling can introduce a variety of errors. This includes a jagged, stair-step appearance in sloping or curved lines, a broken look for thin lines, moire patterns of interference and lost detail or missing objects which are so small they reside between adjacent pixels. The effect that is responsible for those errors is called aliasing.
Anti-aliasing is any technique used to help eliminate such errors or to reduce the negative impact they have on the image. In general, anti-aliasing makes the ray traced image look "smoother". The Antialias=on option or +A switch turns on POV-Ray's anti-aliasing system.
When anti-aliasing is turned on, POV-Ray attempts to "smooth" the errors by shooting more than one viewing ray into each pixel and averaging the results to determine the pixel's apparent color. This technique is called super-sampling and can improve the appearance of the final image but it drastically increases the time required to render a scene since many more calculations have to be done.
POV-Ray gives you the option to use one of two alternate super-sampling methods. The Sampling_Method=n option or +AMn switch selects non-adaptive super-sampling (method 1) or adaptive super-sampling (method 2).
In the default, non-adaptive method (+am1), POV-Ray initially traces one ray per pixel. If the color of a pixel differs from its neighbor (to the left or above) by more than a threshold value, then the pixel is super-sampled by shooting a given, fixed number of additional rays. The default threshold is 0.3 but it may be changed using the Antialias_Threshold=n.n option. When the switches are used, the threshold may optionally follow the +A. For example +A0.1 turns anti-aliasing on and sets the threshold to 0.1.
If this difference is greater than the threshold both pixels are super-sampled. The rgb values are in the range 0.0 to 1.0 thus the most two pixels can differ is 3.0. If the anti-aliasing threshold is 0.0, then every pixel is super-sampled. If the threshold is 3.0, then no anti-aliasing is done. Lower threshold means more anti-aliasing and also more time. Use anti-aliasing for your final version of a picture, not the rough draft. The lower the contrast, the lower the threshold should be. Higher contrast pictures can get away with higher tolerance values. Good values seem to be around 0.2 to 0.4.
When using the non-adaptive method, the default number of super-samples is 9 per pixel, located on a 3x3 grid). The Antialias_Depth=n option or +Rn switch controls the number of rows and columns of samples taken for a super-sampled pixel. For example +R4 would give 4x4=16 samples per pixel.
The second, adaptive super-sampling method starts by tracing four rays at the corners of each pixel. If the resulting colors differ more than the threshold amount additional samples are taken. This is done recursively, i.e. the pixel is divided into four sub-pixels that are separately traced and tested for further subdivision. The advantage of this method is the reduced number of rays that have to be traced. Samples that are common among adjacent pixels and sub-pixels are stored and reused to avoid re-tracing of rays. The recursive character of this method makes it adaptive, i.e. the super-sampling concentrates on those parts of the pixel that are more likely to need super-sampling.
Number of samples per Maximum number of samples
super-sampled pixel for per super-sampled pixel for
+Rn the non-adaptive method the adaptive method
1 1 9
2 4 25
3 9 81
4 16 289
5 25 1089
6 36 4225
7 49 16641
8 64 66049
9 81 263169
You should note that the maximum number of samples is hardly ever reached for a given pixel because of the adaptive sampling. If the adaptive method is used with no anti-aliasing each pixel will be the average of the rays traced at its corners. In most cases it does not make sense to use a recursion level greater than 3.
Another way to reduce aliasing artifacts is to introduce noise into the sampling process. This is called "jittering" and works because the human visual system is much more forgiving to noise than it is to regular patterns. The location of the super-samples is jittered or wiggled a tiny amount when anti-aliasing is used. Jittering is used by default but it may be turned off with the Jitter=off option or -J switch. The amount of jittering can be set with the Jitter_Scale=n.nn option. When using switches the jitter scale may be specified after the +J switch. For example +J0.5 uses half the normal jitter. The default amount of 1.0 is the maximum jitter which will insure that all super-samples remain inside the original pixel. Note that the jittering "noise" is random and non-repeatable so you should avoid using jitter in animation sequences, as the anti-aliased pixels will vary and flicker annoyingly from frame to frame.
The overall syntax of a scene is a file that contains any number of the following items in any order.
See "Language Directives" , "Objects" , "Camera" , "Atmospheric Effects" , and "Global Settings" for details.
POV-Ray has a number of reserved keywords which are listed below.
aa_level fog_alt range aa_threshold fog_offset reciprocal abs fog_type recursion_limit acos frequency red acosh gif reflection adaptive global_settings refraction adc_bailout glowing render agate gradient repeat agate_turb granite rgb all gray_threshold rgbf alpha green rgbft ambient halo rgbt ambient_light height_field right angle hexagon ripples aperture hf_gray_16 rotate arc_angle hierarchy roughness area_light hollow samples asc hypercomplex scale asin if scallop_wave asinh ifdef scattering assumed_gamma iff shadowless atan image_map sin atan2 incidence sine_wave atanh include sinh atmosphere int sky atmospheric_attenuation interpolate sky_sphere attenuating intersection slice average inverse slope_map background ior smooth bicubic_patch irid smooth_triangle black_hole irid_wavelength sor blob jitter specular blue julia_fractal sphere blur_samples lambda spherical_mapping bounded_by lathe spiral box leopard spiral1 box_mapping light_source spiral2 bozo linear spotlight break linear_spline spotted brick linear_sweep sqr brick_size location sqrt brightness log statistics brilliance looks_like str bumps look_at strcmp bumpy1 low_error_factor strength bumpy2 mandel strlen bumpy3 map_type strlwr bump_map marble strupr bump_size material_map sturm camera matrix substr case max superellipsoid caustics max_intersections switch ceil max_iteration sys checker max_trace_level t chr max_value tan clipped_by merge tanh clock mesh test_camera_1 color metallic test_camera_2 color_map min test_camera_3 colour minimum_reuse test_camera_4 colour_map mod text component mortar texture composite nearest_count texture_map concat no tga cone normal thickness confidence normal_map threshold conic_sweep no_shadow tightness constant number_of_waves tile2 control0 object tiles control1 octaves torus cos off track cosh offset transform count omega translate crackle omnimax transmit crand on triangle cube once triangle_wave cubic onion true cubic_spline open ttf cylinder orthographic turbulence cylindrical_mapping panoramic turb_depth debug pattern1 type declare pattern2 u default pattern3 ultra_wide_angle degrees perspective union dents pgm up difference phase use_color diffuse phong use_colour direction phong_size use_index disc pi u_steps distance pigment v distance_maximum pigment_map val div planar_mapping variance dust plane vaxis_rotate dust_type png vcross eccentricity point_at vdot else poly version emitting polygon vlength end pot vnormalize error pow volume_object error_bound ppm volume_rendered exp precision vol_with_light exponent prism vrotate fade_distance pwr v_steps fade_power quadratic_spline warning falloff quadric warp falloff_angle quartic water_level false quaternion waves file_exists quick_color while filter quick_colour width finish quilted wood fisheye radial wrinkles flatness radians x flip radiosity y floor radius yes focal_point rainbow z fog ramp_wave
All reserved words are fully lower case. Therefore it is recommended that your identifiers contain at least one upper case character so it is sure to avoid conflict with reserved words.
The following keywords are in the above list of reserved keywords but are not currently used by POV-Ray however they remain reserved.